# Kubelet

## 1. 개요
**Kubelet**은 쿠버네티스 클러스터의 각 노드(`Node`)에서 실행되는 기본 에이전트로, **API 서버**로부터 전달받은 `PodSpec`(포드 사양)에 따라 컨테이너가 정상적으로 실행되고 유지되도록 관리하는 역할을 수행합니다.

**Kubelet**은 컨트롤 플레인(`Control Plane`)과 워커 노드(`Worker Node`) 사이의 가교 역할을 하며, 노드 수준에서 컨테이너의 생명주기를 관리하고 노드의 상태 정보를 마스터 노드에 보고하는 핵심 컴포넌트입니다.

## 2. 동작 원리 및 메커니즘
**Kubelet**은 기본적으로 **선언적 모델(Declarative Model)**을 따릅니다. 사용자가 `kubectl`을 통해 원하는 상태(`Desired State`)를 정의하면, **Kubelet**은 현재 상태(`Current State`)를 확인하고 두 상태를 일치시키기 위해 필요한 작업을 수행합니다.

### 2.1 워크플로우
1. **`PodSpec` 수신**: **Kubelet**은 **API 서버**를 통해 해당 노드에 할당된 **Pod**의 정의서(`PodSpec`)를 전달받습니다.
2. **런타임 요청**: **Kubelet**은 **CRI**(`Container Runtime Interface`)를 통해 컨테이너 런타임에 컨테이너 생성 및 실행을 요청합니다.
3. **네트워크 및 스토리지 설정**: **Kubelet**의 요청을 받은 컨테이너 런타임이 **CNI**(`Container Network Interface`)를 호출하여 네트워크 IP를 할당하며, 스토리지의 경우 **Kubelet**이 **CSI**(`Container Storage Interface`) 드라이버와 통신하여 볼륨 마운트를 수행합니다.
4. **상태 모니터링**: 컨테이너가 실행되면 지속적으로 헬스 체크를 수행하고 결과를 **API 서버**에 보고합니다.

### 2.2 상호작용 흐름도
| 단계 | 주체 $\rightarrow$ 대상 | 상호작용 내용 | 비고 |
| :--- | :--- | :--- | :--- |
| 1 | **API Server** $\rightarrow$ **Kubelet** | `PodSpec` 전달 (`Watch` 메커니즘) | 어떤 **Pod**를 띄울지 지시 |
| 2 | **Kubelet** $\rightarrow$ **Container Runtime** | **CRI** 호출 (`Create Pod Sandbox`) | 컨테이너 생성 요청 |
| 3 | **Container Runtime** $\rightarrow$ **CNI** | 네트워크 설정 및 IP 할당 | 인프라 자원 연결 |
| 4 | **Kubelet** $\rightarrow$ **API Server** | `Node Status` 및 **Pod** 상태 보고 | `Heartbeat` 전송 |

## 3. 핵심 기능 및 책임

### 3.1 Pod 생명주기 관리
**Kubelet**은 **Pod**의 생성, 실행, 종료 및 재시작을 관리합니다. 컨테이너가 예기치 않게 종료되면 `restartPolicy`에 따라 컨테이너를 다시 시작시켜 가용성을 보장합니다.

### 3.2 헬스 체크 (Probes)
**Kubelet**은 다음과 같은 프로브(`Probe`)를 통해 컨테이너의 상태를 주기적으로 확인합니다.
- **Liveness Probe**: 컨테이너가 살아있는지 확인하며, 실패 시 컨테이너를 재시작합니다.
- **Readiness Probe**: 컨테이너가 트래픽을 받을 준비가 되었는지 확인하며, 실패 시 서비스 엔드포인트에서 제외합니다.
- **Startup Probe**: 애플리케이션의 초기 구동 완료 여부를 확인하여, 구동 중에는 **Liveness/Readiness** 체크를 일시 중단합니다.

### 3.3 노드 상태 보고 및 리소스 관리
- **Node Status**: CPU, 메모리 사용량 및 노드의 `Ready` 상태를 **API 서버**에 보고합니다.
- **리소스 메트릭 수집**: **Kubelet**은 내장된 **cAdvisor**를 통해 컨테이너의 CPU, 메모리 사용량 등 리소스 메트릭을 수집하여 **API 서버**에 보고합니다.
- **Eviction (축출)**: 노드의 메모리나 디스크 공간이 부족해지면(`Pressure` 상태), 우선순위가 낮은 **Pod**를 강제로 종료시켜 노드의 안정성을 확보합니다.

## 4. 인터페이스 상세 설명 (CRI, CNI, CSI)
**Kubelet**은 다양한 벤더의 솔루션을 수용하기 위해 표준화된 인터페이스를 사용합니다.

| 인터페이스 | 풀네임 | 설명 | 역할 |
| :--- | :--- | :--- | :--- |
| **CRI** | Container Runtime Interface | 컨테이너 런타임 표준 인터페이스 | `containerd`, `CRI-O` 등 다양한 런타임과 통신 |
| **CNI** | Container Network Interface | 컨테이너 네트워크 표준 인터페이스 | **Pod**에 IP 할당, 네트워크 네임스페이스 설정 (`Calico`, `Flannel` 등) |
| **CSI** | Container Storage Interface | 컨테이너 스토리지 표준 인터페이스 | 외부 스토리지(`AWS EBS`, `NFS` 등)의 마운트 및 언마운트 관리 |

## 5. 주요 설정 및 구성 요소

### 5.1 인증 및 인가 방식
**Kubelet**은 **API 서버**와 통신하기 위해 강력한 인증 체계를 사용합니다.
- **Kubeconfig**: 정적 파일 형태의 인증서 세트를 사용하여 **API 서버**에 인증합니다. 주로 단일 노드나 테스트 환경에서 사용됩니다.
- **Bootstrap**: 새로운 노드가 클러스터에 조인할 때 사용하는 방식입니다. `bootstrap-kubeconfig`를 통해 임시 토큰으로 인증한 뒤, TLS 부트스트래핑 과정을 거쳐 노드 전용 인증서를 자동으로 발급받습니다.

### 5.2 Kubelet 설정 예시 (`kubelet-config.yaml`)
**Kubelet**의 동작은 설정 파일을 통해 세밀하게 조정할 수 있습니다.

```yaml
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
authentication:
  anonymous:
    enabled: false # 익명 요청 거부
authorization:
  mode: Webhook     # API 서버의 Webhook을 통해 권한 확인
evictionHard:
  memory.available: "100Mi" # 가용 메모리가 100Mi 이하일 때 Pod 축출
  nodefs.available: "10%"   # 루트 파일시스템 가용 공간이 10% 이하일 때 축출
cgroupDriver: "systemd"     # 컨테이너 cgroup 드라이버 설정
clusterDNS:
  - 10.96.0.10
clusterDomain: "cluster.local"
```

## 6. 정적 포드 (Static Pod) 관리
정적 포드는 **API 서버**를 거치지 않고 **Kubelet**이 직접 로컬 파일 시스템의 특정 디렉토리를 감시하여 생성하는 포드입니다.

- **특징**: **API 서버**가 다운되어도 **Kubelet**만 살아있다면 실행 및 유지됩니다.
- **용도**: 주로 `kube-apiserver`, `kube-scheduler`와 같은 컨트롤 플레인 컴포넌트를 배포할 때 사용됩니다.
- **동작**: **Kubelet**은 설정된 `--pod-manifest-path` 경로의 YAML 파일을 주기적으로 스캔하여 포드를 생성합니다. **API 서버**는 이 포드들의 상태를 **Mirror Pod** 형태로 읽어와 사용자에게 보여주기만 합니다.

### 6.1 설정 방법 및 예시
1. **Kubelet 설정**: **Kubelet** 실행 옵션에 `--pod-manifest-path=/etc/kubernetes/manifests`를 추가합니다.
2. **매니페스트 작성**: 해당 경로에 **Pod** 정의 YAML 파일을 생성합니다.

**예시: `/etc/kubernetes/manifests/static-web.yaml`**
```yaml
apiVersion: v1
kind: Pod
metadata:
  name: static-web
  labels:
    role: static-web
spec:
  containers:
  - name: web-container
    image: nginx:latest
    ports:
    - containerPort: 80
```

## 7. 노드 관리 및 트러블슈팅

### 7.1 장애 현상
**Kubelet**에 문제가 발생하면 해당 노드는 `NotReady` 상태로 변경됩니다. 이 경우 **API 서버**는 해당 노드의 **Pod**들을 스케줄링 대상에서 제외하며, 설정에 따라 다른 노드로 **Pod**를 재배치(`Eviction`)합니다.

### 7.2 진단 및 해결 절차
1. **서비스 상태 확인**: **Kubelet** 프로세스가 실행 중인지 확인합니다.
2. **로그 분석**: `journalctl`을 통해 에러 메시지를 확인합니다.
3. **리소스 확인**: 노드의 디스크 공간(`DiskPressure`)이나 메모리(`MemoryPressure`) 부족 여부를 확인합니다.

#### 주요 CLI 명령어
| 명령어 | 설명 |
| :--- | :--- |
| `systemctl status kubelet` | **Kubelet** 서비스의 현재 실행 상태 확인 |
| `journalctl -u kubelet -f` | **Kubelet**의 실시간 로그 모니터링 |
| `kubectl get nodes` | 클러스터 내 노드들의 상태(`Ready`/`NotReady`) 확인 |
| `kubectl describe node <node-name>` | 특정 노드의 상세 이벤트 및 리소스 압박 상태 확인 |

```bash
# 1. Kubelet 서비스 상태 확인
systemctl status kubelet

# 2. Kubelet 실시간 로그 확인
journalctl -u kubelet -f

# 3. 노드 상태 및 이벤트 확인
kubectl get nodes
kubectl describe node <node-name>
```

## 8. 요약 및 비교
**Kubelet**은 노드의 관리자이며, **Kube-proxy**는 네트워크 전달자, **Container Runtime**은 실제 실행기입니다.

| 구분 | Kubelet | Kube-proxy | Container Runtime |
| :--- | :--- | :--- | :--- |
| **역할** | 노드 에이전트 (관리자) | 네트워크 프록시 (전달자) | 컨테이너 실행 엔진 (실행기) |
| **핵심 책임** | **Pod** 생명주기, 헬스 체크 | 서비스 트래픽 라우팅 (`iptables`/`IPVS`) | 이미지 풀링, 컨테이너 생성/삭제 |
| **통신 대상** | **API Server** $\leftrightarrow$ **Runtime** | **API Server** $\rightarrow$ Network | **Kubelet** $\rightarrow$ **Container Runtime** |
| **비유** | 현장 소장 (작업 지시 및 감독) | 안내 데스크 (길 안내) | 실제 작업자 (물건 제작) |